Inside Macintosh: QuickDraw GX Programmer's Overview / Part 2 - The QuickDraw GX Programming Cookbook

Chapter 4 - Using the QuickDraw GX Environment

Exiting QuickDraw GX

This programming recipe discusses how you exit from QuickDraw GX, which you would typically do when closing down your application.

Overview of Recipe Steps

The steps in this recipe show you how to:

1. Dispose of any remaining QuickDraw GX objects
2. Dispose of open windows
3. Exit from QuickDraw GX printing
4. Deallocate your graphics client heap
5. Dispose of your graphics client

Some of the steps in this recipe are optional. For example, you are not required to dispose of all your QuickDraw GX objects (Step 1) before exiting from QuickDraw GX. However, you save memory by always disposing of objects that your application is no longer using.

Functions Used in This Recipe

QuickDraw GX functions used in this recipe:

GXDisposeShape	"Shape Objects" QuickDraw GX Objects
GXDisposeStyle	"Style Objects" QuickDraw GX Objects
GXDisposeInk	"Ink Objects" QuickDraw GX Objects
GXDisposeTransform	"Transform Objects" QuickDraw GX Objects
GXExitPrinting	"Core Printing Features" QuickDraw GX Printing
GXExitGraphics	"QuickDraw GX Memory Management" QuickDraw GX Environment and Utilities
GXDisposeGraphicsClient	"QuickDraw GX Memory Management" QuickDraw GX Environment and Utilities

Standard Macintosh functions used in this recipe:

DisposeWindow	"Window Manager" Macintosh Toolbox Essentials
ExitToShell	"Process Manager" Processes

This recipe gives a brief description of these functions; you can find complete reference information for these functions in the Inside Macintosh suite of books.

Recipe Step Descriptions

In this section each step of the recipe is described individually.

1. Dispose of any remaining QuickDraw GX objects

   The recipes in Chapter 6, "Handling Graphics," and in Chapter 7, "Handling Typography," show you how to create graphics and typographic shapes using QuickDraw GX objects. Whenever your application no longer uses one of these objects, it should dispose of the object with the appropriate function: GXDisposeShape, GXDisposeStyle, GXDisposeInk, GXDisposeTransform, and so on.

   When the user quits your application, your application should use these functions to dispose of any remaining QuickDraw GX objects--for example, objects referenced by global variables--before exiting from QuickDraw GX.

   Also, if your application uses a QuickDraw GX library that requires you to call an initialization function, you might have to call a corresponding exiting function to dispose of any objects that the library uses internally.

2. Dispose of open windows

   The recipes in Chapter 5, "Using Macintosh Windows," show you how to create view port objects and connect them Macintosh windows. When the user closes your application, you should dispose of these Macintosh windows using the standard Macintosh function DisposeWindow.

   (You should dispose of any view port objects connected to the Macintosh window before you dispose the window, as described in Chapter 5.)
3. Exit from QuickDraw GX printing

   The recipe described in "Initializing QuickDraw GX," beginning on page 135, shows you how to initialize QuickDraw GX printing features using the GXInitPrinting function.

   If your application uses this function to initialize QuickDraw GX printing, you must exit the QuickDraw GX printing system before you close your application. You can exit QuickDraw GX printing using the GXExitPrinting function:

   OSErr  myQDGXPrintError;

   myQDGXPrintError = GXExitPrinting();

   This function terminates the QuickDraw GX printing features and disposes of the objects and data structures used internally by QuickDraw GX printing. You cannot call any QuickDraw GX printing functions after you call this function (unless you call GXInitPrinting again).

   The GXExitPrinting function returns a result code of type OSErr. If the function successfully closes QuickDraw GX printing, it returns an noErr result code. If the function fails due to low memory or disk errors, it returns a segmentLoadFailedErr result code.

4. Deallocate your graphics client heap

   In "Initializing QuickDraw GX," beginning on page 135, you allocate a graphics client heap for your application using the GXEnterGraphics function. When closing your application, you deallocate your graphics client heap using the GXExitGraphics function:

   GXExitGraphics();

   This function disposes of all the default data structures that QuickDraw GX has created for your application and deallocates your application's active graphics client heap. You must call this function after calling the GXExitPrinting function described in Step 3.

   If you enabled QuickDraw GX notices as described in the previous recipe, "Setting Up Type Validation and Error Handling," the GXExitGraphics function posts a notice if you haven't disposed of all your application's objects. The function always posts a notice for the first object it encounters. For example:

   GRAPHICS NOTICE: shape not disposed

   The GXExitGraphics function disposes of any objects remaining in your heap for you. However, it's best if you dispose of all unused objects yourself; you can use this function to determine whether you have succeeded in disposing all of your objects and therefore you can determine whether your application is wasting memory on objects that it is no longer using.

5. Dispose of your graphics client

   Once you have deallocated your graphics client heap, you can dispose of your graphics client object using the GXDisposeGraphicsClient function:

   GXDisposeGraphicsClient(myGXClient);

   This function should be the last QuickDraw GX function your application calls. Once you have exited from QuickDraw GX, you can call any exiting functions for the parts of the Macintosh Toolbox that your application uses and then terminate your application

Related Recipes

For information related to exiting QuickDraw GX, see these recipes:

• "Initializing QuickDraw GX," on page 135, shows you how to determine whether QuickDraw GX is available to your application and, if so, how to initialize the graphics and printing parts of QuickDraw GX.
• "Setting Up Type Validation and Error Handling," beginning on page 143, shows you how to complete your initialization of QuickDraw GX to include error handling and debugging facilities.

The recipes in the next chapter, "Using Macintosh Windows," show you how to connect QuickDraw GX objects to a Macintosh window. You should read the recipes in that chapter before you begin to use QuickDraw GX to draw shapes.

The recipes in Chapter 6, "Handling Graphics," and in Chapter 7, "Handling Typography," show you how to create and manipulate images drawn to
a window.

The recipes in Chapter 8, "Printing," show you how to initialize printing objects, including job objects, and how to send images to a printer.